<!DOCTYPE html>
<html lang="zh">

<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
	<meta name="keywords" content="dromara.org" />
	<meta name="description" content="dromara.org" />
	<!-- 网页标签标题 -->
	<title>dromara(Open source organization)</title>
	<link rel="shortcut icon" href="/img/docsite.ico"/>
	<link rel="stylesheet" href="/build/documentation.css" />
</head>
<body>
	<div id="root"><div class="documentation-page" data-reactroot=""><header class="header-container header-container-normal"><div class="header-body"><a href="/en-us/index.html"><img class="logo" src="/img/dromara.png"/></a><div class="search search-normal"><span class="icon-search"></span></div><span class="language-switch language-switch-normal">中</span><div class="header-menu"><img class="header-menu-toggle" src="/img/system/menu_gray.png"/><ul><li class="menu-item menu-item-normal"><a href="/en-us/index.html" target="_self">Home</a><div class="sub-menu"><ul></ul></div></li><li class="menu-item menu-item-normal menu-item-normal-active"><a href="#">Document</a><div class="sub-menu"><ul><li><a href="/en-us/docs/soul/soul.html" target="_self">Soul</a></li><li><a href="/en-us/docs/hmily/index.html" target="_self">Hmily</a></li></ul></div></li><li class="menu-item menu-item-normal"><a href="/en-us/blog/index.html" target="_self">Blog</a><div class="sub-menu"><ul></ul></div></li><li class="menu-item menu-item-normal"><a href="/en-us/community/index.html" target="_self">Community</a><div class="sub-menu"><ul></ul></div></li></ul></div></div></header><section class="content-section"><div class="sidemenu" id="menu"><div class="sidemenu-toggle"><img src="https://img.alicdn.com/tfs/TB1E6apXHGYBuNjy0FoXXciBFXa-200-200.png"/></div><ul><li class="menu-item menu-item-level-1"><span>Soul</span><ul><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/en-us/docs/soul/soul.html" target="_self">Home  </a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/en-us/docs/soul/team.html" target="_self">Team</a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/en-us/docs/soul/db.html" target="_self">Database Design</a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/en-us/docs/soul/config.html" target="_self">Config</a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/en-us/docs/soul/dataSync.html" target="_self">DataSync</a></li><li style="height:36px;overflow:hidden" class="menu-item menu-item-level-2"><a href="/en-us/docs/soul/metaData.html" target="_self">MetaData</a></li><li style="height:864px;overflow:hidden" class="menu-item menu-item-level-2"><span>User Document<img style="transform:rotate(0deg)" class="menu-toggle" src="/img/system/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/setup.html" target="_self">Set up</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/soul-dict.html" target="_self">Dictionary management</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-handle.html" target="_self">Plugin handle explanation</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/user-http.html" target="_self">Http proxy</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/user-dubbo.html" target="_self">Dubbo proxy</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/user-springcloud.html" target="_self">Spring cloud proxy</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/user-sofa.html" target="_self">Sofa rpc proxy</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/selector.html" target="_self">Selector and Rule</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/user-dataSync.html" target="_self">Use data sync</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-contextpath.html" target="_self">Context-path plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-divide.html" target="_self">Divide Plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-dubbo.html" target="_self">Dubbo plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-springcloud.html" target="_self">Spring cloud plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-sofa.html" target="_self">Sofa plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-rateLimiter.html" target="_self">RateLimiter plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-hystrix.html" target="_self">Hystrix plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-sentinel.html" target="_self">Sentinel plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-resilience4j.html" target="_self">Resilience4j plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-monitor.html" target="_self">Monitor plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-waf.html" target="_self">Waf plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-sign.html" target="_self">Sign plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-rewrite.html" target="_self">Rewrite plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/plugin-websocket.html" target="_self">Websocket plugin</a></li></ul></li><li style="height:360px;overflow:hidden" class="menu-item menu-item-level-2"><span>Developer Guide<img style="transform:rotate(0deg)" class="menu-toggle" src="/img/system/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/dev-filter.html" target="_self">Custom filter </a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/dev-plugin.html" target="_self">Custom plugin</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/dev-file.html" target="_self">File and Image</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/dev-iphost.html" target="_self">Custom parsing IP and Host</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/dev-result.html" target="_self">Custom result</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/dev-sign.html" target="_self">Custom sign algorithm</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/dev-client.html" target="_self">Developer soul client</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/dev-thread.html" target="_self">Thread</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/dev-netty.html" target="_self">Soul optimize</a></li></ul></li><li style="height:144px;overflow:hidden" class="menu-item menu-item-level-2"><span>Community<img style="transform:rotate(0deg)" class="menu-toggle" src="/img/system/arrow_down.png"/></span><ul><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/contributor.html" target="_self">Contributor</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/committer.html" target="_self">Committer</a></li><li class="menu-item menu-item-level-3"><a href="/en-us/docs/soul/code-conduct.html" target="_self">Code conduct</a></li></ul></li></ul></li></ul></div><div class="doc-content markdown-body" id="doc-body"><h2>Features</h2>
<ul>
<li>
<p>selector and rule are the key point of soul gateway, you can manage any request with it.</p>
</li>
<li>
<p>this chapter is mainly focus on the concepts of selector and rule and how to use it.</p>
</li>
</ul>
<h2>overview</h2>
<ul>
<li>
<p>one plugin has many selector and a selector has many rules, selector is the first filter of request, and the rule is the final filter.</p>
</li>
<li>
<p>pls consider this, it would be perfect when the plugin executes the request until it reached the config value.</p>
</li>
<li>
<p>selector and rule are designed to execute only when the request meet the specific condition.</p>
</li>
<li>
<p>pls refer to the previous data structure <a href="db.md">database design</a>.</p>
</li>
</ul>
<h2>selector</h2>
<p><img src="https://yu199195.github.io/images/soul/selector.png" alt=""></p>
<ul>
<li>
<p>selector detailed explanation：</p>
<ul>
<li>name：create your selector with a distinguish name.</li>
<li>type：custom flow is customized request, full flow is full request. customized request will be handled by the conditions as below, while  full request won't.</li>
<li>match method: you can combine these conditions with 'and' , 'or' operators.</li>
<li>condition：
<ul>
<li>uri: filter request with uri method and support fuzzy matching (/**).</li>
<li>header: filter request with request header.</li>
<li>query: filter request with query string.</li>
<li>ip: filter request with your real ip.</li>
<li>host: filter request with your real host.</li>
<li>post: not recommend to use.</li>
<li>condition match:
<ul>
<li>match : fuzzy string matching，recommend to combine with uri，support restful matching.（/test/**).</li>
<li>= : if the values are the same, then they match.</li>
<li>regEx : regex matching，match characters in regex expression.</li>
<li>like : string fuzzy matching.</li>
</ul>
</li>
</ul>
</li>
<li>open option：only work with enabled.</li>
<li>print log：it will print the matching log with the open option enabled.</li>
<li>execution order：the smaller will have high priorty to execute among multi-selectors.</li>
</ul>
</li>
<li>
<p>the above picture means: when the prefix of the request uri is <code>/test</code> and the value of <code>module</code> in<code>header</code> is<code>test</code>, it will redirect to this service <code>1.1.1.1:8080</code>.</p>
</li>
<li>
<p>selector advice : combine <code>uri</code> conditon and <code>match</code> prefix（/contextPath）as the first request filter.</p>
</li>
</ul>
<h2>rule</h2>
<p><img src="https://yu199195.github.io/images/soul/rule.png" alt=""></p>
<ul>
<li>
<p>when the request was passed by the seletor, then it will be processed by the rule, the final filter.</p>
</li>
<li>
<p>rule is the final confirmation about how to execute request logically.</p>
</li>
<li>
<p>rule detailed explanation：</p>
<ul>
<li>name：create your selector with a distinguish name.</li>
<li>match method: you can combine these conditions with 'and' , 'or' operators.</li>
<li>condition：
<ul>
<li>uri: filter request with uri method and support fuzzy matching (/**).</li>
<li>header: filter request with request header.</li>
<li>query: filter request with query string.</li>
<li>ip: filter request with your real ip.</li>
<li>host: filter request with your real host.</li>
<li>post: not recommend to use.</li>
<li>condition match:
<ul>
<li>match : fuzzy string matching，recommend to combine with uri，support restful matching.（/test/**）</li>
<li>= : if the values are the same, then they match.</li>
<li>regEx : regex matching，match characters in regex expression.</li>
<li>like : string fuzzy matching.</li>
</ul>
</li>
</ul>
</li>
<li>open option：only work with enabled.</li>
<li>print log：it will print the matching log with the open option enabled.</li>
<li>execution order：the smaller will have high priorty to execute amongmulti-selectors.</li>
<li>handle: different plugin has different execution method, pls refer to the specific one.</li>
</ul>
</li>
<li>
<p>above picture means: when the request <code>uri</code> equals to <code>/http/order/save</code>, it will execute based on this rule，load strategy is <code>random</code>.</p>
</li>
<li>
<p>combine selector means ：when the request <code>uri</code> is <code>/http/order/save</code>, it will be redicted to <code>1.1.1.1:8080</code> by <code>random</code> method.</p>
</li>
<li>
<p>rule advice: combine <code>uri</code> condition with <code>match</code> the real <code>uri path</code> condition as the final filter.</p>
</li>
</ul>
<h2>condition detailed explanation</h2>
<ul>
<li>
<p>uri matching （recommend）</p>
<ul>
<li>
<p>uri matching is based on your request uri, the frontend won't change anything before accessing the gateway.</p>
</li>
<li>
<p>the <code>match</code> filter method is the same with<code>springmvc</code> fuzzy matching.</p>
</li>
<li>
<p>in selector，we recommend to match with the prefix of uri, and use the specific path in rule.</p>
</li>
<li>
<p>when changing the match method, the matching field name can be filled randomly, but make sure the match value must be correct.</p>
</li>
</ul>
</li>
<li>
<p>header matching</p>
<ul>
<li>header matches with your <code>http</code> request header value.</li>
</ul>
</li>
<li>
<p>query matching</p>
<ul>
<li>
<p>it matches the query string in your uri, such as: /test?a=1&amp;&amp;b=2.</p>
</li>
<li>
<p>so you can add a new condition, choose query method: a   =  1.</p>
</li>
</ul>
</li>
<li>
<p>ip matching</p>
<ul>
<li>
<p>it matches the ip of the http caller.</p>
</li>
<li>
<p>especially in the waf plugin, if you find some ip is unsafe, you can add a match condition with this ip, then it can't access any more.</p>
</li>
<li>
<p>if you use nginx proxy before soul, you can get the right ip with refering to <a href="dev-iphost.md">dev-iphost</a></p>
</li>
</ul>
</li>
<li>
<p>host matching</p>
<ul>
<li>
<p>it matches the host of http caller.</p>
</li>
<li>
<p>especially in waf plugin, if you find some host is unsafe, you can add a match condition with this host, then it can't access any more.</p>
</li>
<li>
<p>if you use nginx proxy before soul, you can get the right ip with refering to <a href="dev-iphost.md">dev-iphost</a></p>
</li>
</ul>
</li>
<li>
<p>post matching</p>
<ul>
<li>not recommend to use.</li>
</ul>
</li>
</ul>
</div></section><footer class="footer-container"><div class="footer-body"><img src="/img/dromara.png"/><div class="cols-container"><div class="col col-12"><h3>Disclaimer</h3><p>Any unit or individual reprint all relevant information of this website, please indicate the source.</p></div><div class="col col-6"><dl><dt>Document</dt><dd><a href="/en-us/docs/soul/soul.html" target="_self">Overview </a></dd><dd><a href="/en-us/docs/soul/soul.html" target="_self">Stat up</a></dd><dd><a href="/en-us/docs/soul/soul.html" target="_self">Developer Guide</a></dd></dl></div><div class="col col-6"><dl><dt>Resource</dt><dd><a href="/en-us/blog/index.html" target="_self">Blog</a></dd><dd><a href="/en-us/community/index.html" target="_self">Community</a></dd></dl></div></div><div class="copyright"><span>Copyright ©2020 xiaoyu@apache.org by xiaoyu</span></div></div></footer></div></div>
	<script src="https://f.alicdn.com/react/15.4.1/react-with-addons.min.js"></script>
	<script src="https://f.alicdn.com/react/15.4.1/react-dom.min.js"></script>
	<script>
		window.rootPath = '';
  </script>
	<script src="/build/documentation.js"></script>
</body>
</html>